Langchain4j - Skill 简单案例

Skill 简介

是什么?

Agent Skill 本质上是给 AI 打包好的 “专业能力模块”,一个包含指令、脚本和资源的文件夹,让 AI 从 “会聊天” 变成 “会干活”。它解决了传统 Prompt 每次重复输入、输出不稳定的痛点,把工作流程固化成可复用的技能包。在技术形态上,一个 Skill 通常是以标准化的 Markdown / YAML 文件形式存在(例如包含元数据的 SKILL.md),它集成了:

  • 触发意图:定义什么场景下该激活此技能。
  • 流程规范:告诉 LLM 具体的步骤逻辑(如:“重构代码时,必须先跑单元测试,再遵循 DRY 原则,最后检查类型定义”)。
  • 上下文知识:特定项目或领域的专有信息。
  • 可执行脚本/工具引用:附带的本地 Python/Shell 脚本或命令行调用范式。


解决什么问题?

在 Agent Skill 出现之前,让 AI 执行复杂任务主要依赖系统提示词(System Prompt)或动态检索(RAG)。这带来了三个痛点,也是 Skill 出现的关键原因:

  • 解决上下文窗口爆炸与 Token 成本过高问题。如果把所有业务流程和所有工具的完整说明都一股脑写入全局 Prompt,每次对话都会消耗成千上万 Token,且容易导致模型 “迷失在细节中”。Skill 引入了渐进式暴露机制:初始时只加载 Skill 的 “名称与简短描述”(仅耗费百来 Token),只有当用户意图匹配时,Agent 才按需将具体的 SKILL.md 内容展开加载到上下文。
  • 解决 AI “懂工具但不懂业务逻辑/规范” 的问题。即便 AI 拥有调用 API 的能力,它依然不知道你团队内部的约束(例如:“代码提交前必须包含哪些 CI 检查”或“如何按照公司的特定架构模式编写业务代码”)。Skill 将“知识”与“步骤”封装在一起,约束 Agent 行为。
  • 解决可复用性与模块化问题。以前针对特定场景的复杂 Prompt 很难在团队间共享与版本控制。Skill 提供了轻量化、类似 “软件包” 的目录结构,让知识和工作流可以像 Git 仓库一样进行版本管控、团队协同与生态分发。


Java 领域的支持

目前,LangChain4j(>=1.12.x)和 Spring AI(2.0.0+)目前都已原生支持或通过标准扩展支持了 Agent Skill(以 SKILL.md 规范为核心)。针对 Java AI 生态的两大主流框架,实现细节与技术路线有所差异:

  • LangChain4j 的支持情况:
    • LangChain4j 将 Skill 抽象为一种渐进式动态加载上下文与工具链的机制。
    • 延迟加载(Lazy Context Injection):启动时只扫描 SKILL.md 的 Frontmatter(即 YAML 头部定义的 name 和 description),并将其注册为路由元数据(非常节省 Prompt Token)。
    • 动态激活:当 LLM 判定需要执行某个复合任务(如 process-order)时,会自动触发 Skill 加载工具。
    • 指令注入:SKILL.md 正文中的 Markdown 操作规范(SOP)会被当作动态上下文注入当前对话,LLM 随后遵照 SOP 去依次调用关联的 Java @Tool 方法。
  • Spring AI 的支持:
    • Spring AI 将 Skill 接入到了其原有的 Function Call / Tool / Advisor 架构 体系中,不仅支持经典的 Spring Bean 声明式技能,还支持直接解析类路径或文件系统中的 SKILL.md 规范。Spring AI 的 AgentUtils 框架通过动态 Tool 机制,把 Skill 转化成系统内部可调用的“高阶元工具”。LLM 触发 Skill 后,SKILL.md 的内容会作为 Tool Result 返回给模型,驱动模型在下一步的推理链中按照 SOP 执行后续行动。
    • 配置与使用方式:
      • 定义静态 Skill:将封装好的 Skill 文件夹置于项目资源目录或外部存储服务中。
      • Auto-Configuration(自动装配):Spring AI 自动扫描容器中的 SkillManager / AgentSkill 节点。
      • 与 MCP / Functions 协同:在 Spring AI 中,Skill 通常用来编排那些通过 @Bean 注入的 FunctionCallback 或者从外部 MCP Server 导入过来的原生 Tools。
维度 LangChain4j Spring AI
支持方式 原生抽象组件,基于 SKILL.md 文件路由与 Tool 编排 结合 Advisor/Tool 机制与 agentskills.io 规格整合
技能来源 本地 Classpath 文件系统、代码动态注册 Spring Bean、本地文件、外部代理技能仓库
执行载体 Java 本地 @Tool 方法、嵌入式 ToolProvider Spring FunctionCallback、Spring Bean、MCP Tools
主要优势 代码侵入性极低,轻量,适合构建纯 Java 智能体(Agent) 企业级扩展性强,天然整合 Spring 生态的配置管理与安全体系

在当前的 Java AI 体系中,Skill 已经被两大框架作为编排复杂业务 SOP 的标准载体。在实际落地时,往往采用 “MCP 负责提供底层安全的接口连接 + Skill 文件负责定义上层业务逻辑 SOP” 的组合模式,直接在 Java 项目中即可快速落地。


Hello World 案例

为了帮助你快速验证,我们以下面 “客户订单处理场景” 构建一个最简 Langchain4j 示例。

  • AI 本身并不知道订单处理的合规流转顺序;
  • 我们通过一个包含 SKILL.md 的技能包,告知 AI 在处理订单时,必须按照 “验证订单 -> 预留库存 -> 扣款 -> 发确认邮件” 的 SOP 执行;
  • 当用户发出指令时,LangChain4j 会自动激活 Skill,并将 Markdown SOP 的指示约束传递给 LLM 逐步调用对应的 Java 工具(@Tool)。


核心代码

依赖配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<dependencies>
<!-- LangChain4j 核心依赖 -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j</artifactId>
</dependency>

<!-- 支持大模型的依赖(这里以 OpenAI API 为例,兼容 DeepSeek / Qwen 等) -->
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-open-ai</artifactId>
</dependency>

<!-- 这里主使用其默认的日志打印功能(logback) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>

Skill 标准元文件:src/main/resources/skills/process-order/SKILL.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
name: process-order
description: 客户订单处理与异常处理的完整标准流程 SOP
---

### 订单处理规范指南:
请严格遵循以下步骤顺序来处理用户提交的订单:

1. **第一步**:首先调用 `validateOrder` 校验订单 ID 是否合法。
2. **第二步**:仅当校验通过后,调用 `reserveInventory` 预留库存。
3. **第三步**:库存预留成功后,调用 `chargePayment` 进行订单扣款。
4. **第四步**:扣款完成后,调用 `sendConfirmationEmail` 向用户发送确认邮件。

*异常控制规则*:
在上述任何环节若提示“失败”或出现异常,必须**中断**后续动作,并立即调用 `rollbackOrder` 执行回滚,最后向用户报告失败原因。

简易 SKILL.md 解析器与实体类:AgentSkill。因为 SKILL.md 本质是一个带 Frontmatter (YAML) 的 Markdown 文件,我们可以写一个极其轻量的加载器读取它(这也是 LangChain4j 社区官方推荐的扩展范式):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;

public class AgentSkill {

private final String name;
private final String description;
private final String instructions; // SOP 内容

public AgentSkill(String name, String description, String instructions) {
this.name = name;
this.description = description;
this.instructions = instructions;
}

public static AgentSkill loadFromClasspath(String resourcePath) {
try (InputStream is = AgentSkill.class.getClassLoader().getResourceAsStream(resourcePath)) {
if (is == null) {
throw new IllegalArgumentException("未找到 Skill 文件: " + resourcePath);
}
String content = new String(is.readAllBytes(), StandardCharsets.UTF_8);

// 解析 YAML Frontmatter 和正文 Markdown
String[] parts = content.split("---", 3);
if (parts.length < 3) {
return new AgentSkill("unknown", "Skill Description", content);
}

String yaml = parts[1];
String instructions = parts[2].trim();

String name = parseYamlValue(yaml, "name");
String description = parseYamlValue(yaml, "description");

return new AgentSkill(name, description, instructions);
} catch (IOException e) {
throw new RuntimeException("读取 Skill 资源失败", e);
}
}

private static String parseYamlValue(String yaml, String key) {
for (String line : yaml.split("\n")) {
if (line.trim().startsWith(key + ":")) {
return line.substring(line.indexOf(":") + 1).trim();
}
}
return "";
}

public String getName() { return name; }
public String getDescription() { return description; }
public String getInstructions() { return instructions; }
}

定义供 Skill 在 SOP 流程中调用的工具:OrderTools.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
import dev.langchain4j.agent.tool.Tool;

public class OrderTools {

@Tool("校验订单ID格式与有效性")
public String validateOrder(String orderId) {
System.out.println(" --> [Java Tool] 执行: 正在验证订单ID: " + orderId);
if (orderId != null && orderId.startsWith("ORD")) {
return "SUCCESS: 订单 " + orderId + " 校验通过";
}
return "FAIL: 订单 " + orderId + " 无效(格式不正确)";
}

@Tool("为指定订单预留商品库存")
public String reserveInventory(String orderId) {
System.out.println(" --> [Java Tool] 执行: 正在预留库存,订单: " + orderId);
if ("ORD999".equalsIgnoreCase(orderId)) {
return "FAIL: 库存不足,预留失败";
}
return "SUCCESS: 库存预留成功";
}

@Tool("执行订单扣款操作")
public String chargePayment(String orderId) {
System.out.println(" --> [Java Tool] 执行: 正在扣款,订单: " + orderId);
return "SUCCESS: 扣款成功";
}

@Tool("发送订单处理结果通知邮件")
public String sendConfirmationEmail(String orderId) {
System.out.println(" --> [Java Tool] 执行: 发送确认邮件,订单: " + orderId);
return "SUCCESS: 邮件已成功发送";
}

@Tool("订单处理失败时执行事务回滚")
public String rollbackOrder(String orderId) {
System.out.println(" --> [Java Tool] 执行: 触发回滚补偿机制,订单: " + orderId);
return "SUCCESS: 事务已安全回滚";
}
}

动态工具提供者:OrderToolProvider,LangChain4j 提供了强大的 ToolProvider 机制。如果 Skill 匹配,才将工具暴露给 LLM,实现低 Token 开销与动态调配:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
import dev.langchain4j.agent.tool.ToolSpecification;
import dev.langchain4j.agent.tool.ToolSpecifications;
import dev.langchain4j.service.tool.*;
import java.lang.reflect.Method;
import java.util.List;

public class OrderToolProvider implements ToolProvider {

private final OrderTools orderTools = new OrderTools();

@Override
public ToolProviderResult provideTools(ToolProviderRequest request) {
ToolProviderResult.Builder builder = ToolProviderResult.builder();

// 获取用户本次发送的消息
String userMessage = request.userMessage() != null ? request.userMessage().singleText() : "";

// 简单意图路由(实际工程中可使用向量检索/ Intent Classifier):
// 只有当用户意图包含“订单”或“ORD”时,才暴露 OrderTools
if (userMessage.contains("订单") || userMessage.contains("ORD")) {
System.out.println("\n[ToolProvider] 识别到订单意图,激活暴露 OrderTools 工具集");

List<ToolSpecification> toolSpecifications = ToolSpecifications.toolSpecificationsFrom(orderTools);
for (ToolSpecification toolSpec : toolSpecifications) {
ToolExecutor toolExecutor = new DefaultToolExecutor(orderTools, findMethod(orderTools.getClass(), toolSpec.name()));
builder.add(toolSpec, toolExecutor);
}
} else {
System.out.println("\n[ToolProvider] 未识别到订单意图,【不暴露】任何 Tool");
}
return builder.build();
}

private Method findMethod(Class<?> clazz, String methodName) {
for (Method method : clazz.getDeclaredMethods()) {
if (method.getName().equals(methodName)) {
return method;
}
}
throw new IllegalArgumentException("未找到方法: " + methodName);
}
}

定义 AI 接口:OrderAssistant

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

public interface OrderAssistant {

@SystemMessage("""
你是一个专业的订单处理 Agent。
你需要严格遵循以下【标准业务 SOP 规范】来执行用户指令:

{{skillInstruction}}
""")
String chat(@UserMessage String userMessage, @V("skillInstruction") String skillInstruction);
}

主程序入口:OrderProcessingApp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;

public class OrderProcessingApp {

public static void main(String[] args) {
// 1. 初始化 ChatModel
ChatModel model = OpenAiChatModel.builder()
.baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
.apiKey(System.getenv("QWEN_API_KEY"))
.modelName("qwen3.7-plus")
.temperature(0.0) // SOP 执行建议设为 0,确保行为的确定性
.logRequests(true)
.logResponses(true)
.build();

// 2. 加载类路径下的 SKILL.md 文件 (skills/process-order/SKILL.md)
AgentSkill processOrderSkill = AgentSkill.loadFromClasspath("skills/process-order/SKILL.md");

System.out.println("加载技能成功: " + processOrderSkill.getName());
System.out.println("技能描述: " + processOrderSkill.getDescription());

// 3. 构建原生的 AI Service
OrderAssistant assistant = AiServices.builder(OrderAssistant.class)
.chatModel(model)
//.tools(new OrderTools())
.toolProvider(new OrderToolProvider()) // 只有识别到要执行订单 Skill 时才暴露订单 Tool
.build();

// 4. 运行测试:传入 Skill 的 SOP 规范与用户指令
System.out.println("\n=========== 测试场景 1:正常成功流转 ===========");
String response1 = assistant.chat("请帮我处理一下订单 ORD001", processOrderSkill.getInstructions());
System.out.println("\n[LLM 最终回复]:\n" + response1);

System.out.println("\n=========== 测试场景 2:中途失败触发补偿回滚 ===========");
String response2 = assistant.chat("请帮我处理一下订单 ORD999", processOrderSkill.getInstructions());
System.out.println("\n[LLM 最终回复]:\n" + response2);

System.out.println("\n=========== 测试场景 3:不暴露 Tool 的场景(普通闲聊) ===========");
String response3 = assistant.chat("你们公司营业时间是什么时候?", processOrderSkill.getInstructions());
System.out.println("\n[LLM 最终回复]:\n" + response3);
}
}


测试结果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
加载技能成功: process-order
技能描述: 客户订单处理与异常处理的完整标准流程 SOP

=========== 测试场景 1:正常成功流转 ===========

[ToolProvider] 🎯 识别到订单意图,激活暴露 OrderTools 工具集
01:25:54.607 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP request:
- method: POST
- url: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
- headers: [Authorization: Beare...xY], [User-Agent: langchain4j-openai], [Content-Type: application/json]
- body: {
"model" : "qwen3.7-plus",
"messages" : [ {
"role" : "system",
"content" : "你是一个专业的订单处理 Agent。\n你需要严格遵循以下【标准业务 SOP 规范】来执行用户指令:\n\n### 订单处理规范指南:\n请严格遵循以下步骤顺序来处理用户提交的订单:\n\n1. **第一步**:首先调用 `validateOrder` 校验订单 ID 是否合法。\n2. **第二步**:仅当校验通过后,调用 `reserveInventory` 预留库存。\n3. **第三步**:库存预留成功后,调用 `chargePayment` 进行订单扣款。\n4. **第四步**:扣款完成后,调用 `sendConfirmationEmail` 向用户发送确认邮件。\n\n*异常控制规则*:\n在上述任何环节若提示“失败”或出现异常,必须**中断**后续动作,并立即调用 `rollbackOrder` 执行回滚,最后向用户报告失败原因。\n"
}, {
"role" : "user",
"content" : "请帮我处理一下订单 ORD001"
} ],
"temperature" : 0.0,
"stream" : false,
"tools" : [ {
"type" : "function",
"function" : {
"name" : "validateOrder",
"description" : "校验订单ID格式与有效性",
"parameters" : {
"type" : "object",
"properties" : {
"orderId" : {
"type" : "string"
}
},
"required" : [ "orderId" ]
}
}
},
...
}

01:25:58.066 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], [content-length: 1327], [content-type: application/json], ...
- body: {"model":"qwen3.7-plus","id":"chatcmpl-8e16df9f-d9a6-9142-ab19-709becd09ad7","choices":[{"message":{"tool_calls":[{"index":0,"id":"call_6a91f091b3534572b1596b2b","type":"function","function":{"name":"validateOrder","arguments":"{\"orderId\": \"ORD001\"}"}}],"role":"assistant","content":"我来帮你处理订单 ORD001。首先,我需要校验订单 ID 是否合法。\n\n","reasoning_content":"用户要求处理订单 ORD001。根据标准业务 SOP 规范,我需要按照以下步骤执行:\n\n1. 第一步:调用 validateOrder 校验订单 ID 是否合法\n2. 第二步:校验通过后,调用 reserveInventory 预留库存\n3. 第三步:库存预留成功后,调用 chargePayment 进行订单扣款\n4. 第四步:扣款完成后,调用 sendConfirmationEmail 发送确认邮件\n\n异常控制规则:任何环节失败,必须中断后续动作,立即调用 rollbackOrder 执行回滚,并向用户报告失败原因。\n\n现在我需要执行第一步:调用 validateOrder 校验订单 ORD001。"},"index":0,"finish_reason":"tool_calls"}],"created":1789838755,"object":"chat.completion","usage":{"total_tokens":870,"completion_tokens":186,"prompt_tokens":684,"completion_tokens_details":{"reasoning_tokens":134,"text_tokens":186},"prompt_tokens_details":{"cached_tokens":0,"text_tokens":684}}}

--> [Java Tool] 执行: 正在验证订单ID: ORD001
01:25:58.119 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP request:
- method: POST
- url: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
- headers: [Authorization: Beare...xY], [User-Agent: langchain4j-openai], [Content-Type: application/json]
- body: {
"model" : "qwen3.7-plus",
"messages" : [ {
"role" : "system",
"content" : "你是一个专业的订单处理 Agent。\n你需要严格遵循以下【标准业务 SOP 规范】来执行用户指令:\n\n### 订单处理规范指南:\n请严格遵循以下步骤顺序来处理用户提交的订单:\n\n1. **第一步**:首先调用 `validateOrder` 校验订单 ID 是否合法。\n2. **第二步**:仅当校验通过后,调用 `reserveInventory` 预留库存。\n3. **第三步**:库存预留成功后,调用 `chargePayment` 进行订单扣款。\n4. **第四步**:扣款完成后,调用 `sendConfirmationEmail` 向用户发送确认邮件。\n\n*异常控制规则*:\n在上述任何环节若提示“失败”或出现异常,必须**中断**后续动作,并立即调用 `rollbackOrder` 执行回滚,最后向用户报告失败原因。\n"
}, {
"role" : "user",
"content" : "请帮我处理一下订单 ORD001"
}, {
"role" : "assistant",
"content" : "我来帮你处理订单 ORD001。首先,我需要校验订单 ID 是否合法。\n\n",
"tool_calls" : [ {
"id" : "call_6a91f091b3534572b1596b2b",
"type" : "function",
"function" : {
"name" : "validateOrder",
"arguments" : "{\"orderId\": \"ORD001\"}"
}
} ]
}, {
"role" : "tool",
"tool_call_id" : "call_6a91f091b3534572b1596b2b",
"content" : "SUCCESS: 订单 ORD001 校验通过"
} ],
...
}

01:25:59.385 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], [content-length: 767], [content-type: application/json], ...
- body: {"model":"qwen3.7-plus","id":"chatcmpl-f1abd10a-e47f-94fa-93de-5279c98d3fc7","choices":[{"message":{"tool_calls":[{"index":0,"id":"call_22f26ae98de64bd88fd8442d","type":"function","function":{"name":"reserveInventory","arguments":"{\"orderId\": \"ORD001\"}"}}],"role":"assistant","content":"订单校验通过!接下来为您预留商品库存。\n\n","reasoning_content":"订单校验通过了,接下来按照 SOP 第二步,调用 reserveInventory 预留库存。"},"index":0,"finish_reason":"tool_calls"}],"created":1789838758,"object":"chat.completion","usage":{"total_tokens":822,"completion_tokens":60,"prompt_tokens":762,"completion_tokens_details":{"reasoning_tokens":17,"text_tokens":60},"prompt_tokens_details":{"cached_tokens":512,"text_tokens":762}}}

--> [Java Tool] 执行: 正在预留库存,订单: ORD001
01:25:59.388 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP request:
...
01:26:02.254 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], [content-length: 1146], [content-type: application/json], ...
- body: {"model":"qwen3.7-plus","id":"chatcmpl-e869ef06-ac7e-91e1-9f9a-...: \"ORD001\"}"}}],"role":"assistant","content":"库存预留成功!现在进行订单扣款...

--> [Java Tool] 执行: 正在扣款,订单: ORD001
01:26:02.257 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP request:
...
01:26:03.790 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], [content-length: 734], [content-type: application/json],...
- body: {"model":"qwen3.7-plus",..."content":"扣款成功!最后为您发送订单确认邮件。\n\n","reasoning_content":"扣款成功,现在执行第四步:发送确认邮件。"...

--> [Java Tool] 执行: 发送确认邮件,订单: ORD001
01:26:03.793 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP request:
01:26:05.940 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], ...

[LLM 最终回复]:
✅ **订单 ORD001 处理完成!**

以下是处理结果汇总:

| 步骤 | 操作 | 状态 |
|------|------|------|
| 第一步 | 订单校验 | ✅ 通过 |
| 第二步 | 库存预留 | ✅ 成功 |
| 第三步 | 订单扣款 | ✅ 成功 |
| 第四步 | 发送确认邮件 | ✅ 已发送 |

您的订单已成功处理,确认邮件已发送至您的邮箱,请注意查收。如有其他问题,请随时联系我!


=========== 测试场景 2:中途失败触发补偿回滚 ===========
...

[LLM 最终回复]:
---

### 📋 订单处理报告

**订单编号**:ORD999
**处理结果**:❌ **处理失败**

**详细过程**:
1. ✅ **订单校验**:通过
2. ❌ **库存预留**:失败(原因:**库存不足**)
3. ⏹️ **订单扣款**:已中断
4. ⏹️ **发送确认邮件**:已中断
5. ✅ **事务回滚**:已安全回滚

**失败原因**:
在为您预留商品库存时,系统提示**库存不足**,导致无法继续后续流程。

**后续建议**:
由于已触发异常控制规则,本次订单的所有操作已安全回滚,不会产生任何扣款。建议您稍后重新尝试下单,或联系客服确认该商品的库存情况。

如有其他问题,请随时告诉我!


=========== 测试场景 3:不暴露 Tool 的场景(普通闲聊) ===========

[ToolProvider] 🚫 未识别到订单意图,【不暴露】任何 Tool
01:26:18.027 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP request:
- method: POST
- url: https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
- headers: [Authorization: Beare...xY], [User-Agent: langchain4j-openai], [Content-Type: application/json]
- body: {
"model" : "qwen3.7-plus",
"messages" : [ {
"role" : "system",
"content" : "你是一个专业的订单处理 Agent。\n你需要严格遵循以下【标准业务 SOP 规范】来执行用户指令:\n\n### 订单处理规范指南:\n请严格遵循以下步骤顺序来处理用户提交的订单:\n\n1. **第一步**:首先调用 `validateOrder` 校验订单 ID 是否合法。\n2. **第二步**:仅当校验通过后,调用 `reserveInventory` 预留库存。\n3. **第三步**:库存预留成功后,调用 `chargePayment` 进行订单扣款。\n4. **第四步**:扣款完成后,调用 `sendConfirmationEmail` 向用户发送确认邮件。\n\n*异常控制规则*:\n在上述任何环节若提示“失败”或出现异常,必须**中断**后续动作,并立即调用 `rollbackOrder` 执行回滚,最后向用户报告失败原因。\n"
}, {
"role" : "user",
"content" : "你们公司营业时间是什么时候?"
} ],
"temperature" : 0.0,
"stream" : false
}

01:26:23.041 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], [content-length: 1792], [content-type: application/json], ...
- body: {"model":"qwen3.7-plus","id":"chatcmpl-3a8eae9c-4250-935e-b71a-d3eaf3bc01d5","choices":[{"message":{"content":"您好!我是专业的订单处理 Agent,全天候 24 小时在线为您服务。\n\n如果您有订单需要处理,请随时提供订单 ID,我将严格按照标准业务规范为您办理。请问有什么订单需要我帮您处理吗?","reasoning_content":"用户询问的是“你们公司营业时间是什么时候?”。\n这是一个关于公司营业时间的问题,与订单处理无关。\n作为订单处理 Agent,我的主要职责是处理订单。对于非订单处理相关的问题,我应该礼貌地回答,或者说明我的主要职责。\n不过,作为一个AI,我没有具体的“公司营业时间”,我是24小时在线的。\n我可以回答:“您好!作为一个人工智能助手,我24小时在线为您服务。如果您有订单需要处理,请随时告诉我订单ID,我将严格按照标准业务SOP规范为您处理。”\n或者直接回答营业时间(如果假设一个通用的,但最好说明自己是AI)。\n结合角色设定:“你是一个专业的订单处理 Agent。”\n我可以这样回答:“您好!我是专业的订单处理 Agent,全天候 24 小时在线为您服务。如果您有订单需要处理,请提供订单 ID,我将立即为您办理。”\n这样既回答了问题,又引导回我的核心职责。\n不需要调用任何工具。\n直接回复。","role":"assistant"},"index":0,"finish_reason":"stop"}],"created":...,"object":"chat.completion","usage":{"total_tokens":447,"completion_tokens":251,"prompt_tokens":196,"completion_tokens_details":{"reasoning_tokens":201,"text_tokens":251},"prompt_tokens_details":{"cached_tokens":0,"text_tokens":196}}}


[LLM 最终回复]:
您好!我是专业的订单处理 Agent,全天候 24 小时在线为您服务。

如果您有订单需要处理,请随时提供订单 ID,我将严格按照标准业务规范为您办理。请问有什么订单需要我帮您处理吗?

Process finished with exit code 0

测试中,我们看到:

  • 场景 1和 2(暴露 Tool):Prompt Tokens 达到 684,带上了完整的 Function Definition 模式。
  • 场景 3(不暴露 Tool):Prompt Tokens 仅有 196(节约了约 71% 的输入 Token)。对闲聊或无意图请求屏蔽工具,显著降低了 LLM API 的单次响应成本与耗时。在未识别到特定意图时不向模型透出真实 API 的 Schema,杜绝了非相关对话中被 Prompt 注入(Prompt Injection)误触发敏感接口(如扣款、发邮件)的风险。
  • 在场景 1 的第二次请求日志中,prompt_tokens_details 出现了 cached_tokens: 512。LangChain4j 配合阿里云 DashScope 兼容接口,在多轮 ReAct 交互中触发了服务端的 Prompt Cache(KV 缓存)。虽然 Agent 经历多轮 HTTP 往返(RTT),但系统 Prompt 及前面的历史消息被命中缓存,大大降低了高频工具调用时的推理延迟与计费。
  • 从场景 3 日志看,即使未暴露 Tool,System Prompt 依然携带了“订单处理规范指南”的文字。若希望进一步节省 Token,可以在识别为闲聊时,连同 System Prompt 中的 SOP 正文也一并置空/替换为普通通用 Prompt。另外,在场景 1 和场景 2 的最终回复中,LLM 输出了漂亮 Markdown 格式报告。如果下游系统(如前端 UI)需要解析结构化状态,可利用 LangChain4j 的 AiServices 返回值对象(DTO)或在 Prompt 中规范 JSON 输出,这样更利于系统展示。


多个 skill 案例

当从单个 Skill 扩展到多个 Skill(例如:在包含 “处理订单”的基础上,再新增一个 “退款申请 refund-request” 或 “开具发票 issue-invoice”)时,核心问题变成了:系统如何让 LLM 在几十上百个 Skill 中,只选择并加载当前需要的那个 Skill,从而避免 Token 爆表?这就用到了前文提到的关键机制——渐进式暴露与元数据路由。


Skill 文件组织结构

1
2
3
4
5
6
7
8
src/main/resources/
└── skills/
├── process-order/ # Skill 1:订单处理
│ └── SKILL.md
├── refund-request/ # Skill 2:退款申请 (新增)
│ └── SKILL.md
└── issue-invoice/ # Skill 3:开具发票 (新增)
└── SKILL.md

新增的 skills/refund-request/SKILL.md 示例:

1
2
3
4
5
6
7
8
9
---
name: refund-request
description: 处理客户商品退款与退货审核的标准流程 SOP
---

### 退款处理规范指南:
1. **第一步**:调用 `checkEligibility` 检查订单是否满足 7 天无理由或退货条件。
2. **第二步**:若符合条件,调用 `generateReturnLabel` 生成退货物流单。
3. **第三步**:确认收到退货后,调用 `executeRefund` 执行退款并更新状态。


关键的两阶段路由

为了不让所有 SKILL.md 的完整 SOP 内容同时塞进 System Prompt,工程上会分为两个阶段:

1
2
3
4
5
6
7
[用户输入] 
│
▼
1. 【路由阶段】:LLM 只看所有 Skill 的 "name" + "description" 简短清单(仅消耗几十 Token)
│
▼
2. 【激活阶段】:判定匹配某 Skill 后,才把该 Skill 对应的 "SKILL.md 正文 SOP" 注入 System,并暴露对应的 Tool


多 Skill 实现代码

第一,扩展 AgentSkill 加载器(支持加载目录下的所有 Skill):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import java.io.IOException;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;

public class AgentSkill {

private final String name;
private final String description;
private final String instructions;

public AgentSkill(String name, String description, String instructions) {
this.name = name;
this.description = description;
this.instructions = instructions;
}

public static AgentSkill loadFromClasspath(String resourcePath) {
try (InputStream is = AgentSkill.class.getClassLoader().getResourceAsStream(resourcePath)) {
if (is == null) {
throw new IllegalArgumentException("未找到 Skill 文件: " + resourcePath);
}
String content = new String(is.readAllBytes(), StandardCharsets.UTF_8);

String[] parts = content.split("---", 3);
if (parts.length < 3) {
return new AgentSkill("unknown", "Skill Description", content);
}

String yaml = parts[1];
String instructions = parts[2].trim();

String name = parseYamlValue(yaml, "name");
String description = parseYamlValue(yaml, "description");

return new AgentSkill(name, description, instructions);
} catch (IOException e) {
throw new RuntimeException("读取 Skill 资源失败", e);
}
}

private static String parseYamlValue(String yaml, String key) {
for (String line : yaml.split("\n")) {
if (line.trim().startsWith(key + ":")) {
return line.substring(line.indexOf(":") + 1).trim();
}
}
return "";
}

public String getName() { return name; }
public String getDescription() { return description; }
public String getInstructions() { return instructions; }
}

构建 SkillManager 技能注册表:用于集中管理系统中所有的 Skill,并生成给 LLM 看的 “轻量级技能目录”。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
import java.util.*;

public class SkillManager {

private final Map<String, AgentSkill> skillMap = new HashMap<>();

public void registerSkill(AgentSkill skill) {
skillMap.put(skill.getName(), skill);
}

public AgentSkill getSkill(String name) {
return skillMap.get(name);
}

/**
* 生成极简的技能清单,用于放入 System Prompt 中供 LLM 进行路由选择
* 消耗极少 Token (例如:- process-order: 处理订单流程...)
*/
public String getSkillSummaryList() {
StringBuilder sb = new StringBuilder();
for (AgentSkill skill : skillMap.values()) {
sb.append("- ").append(skill.getName()).append(": ").append(skill.getDescription()).append("\n");
}
return sb.toString();
}
}

定义全量底层工具库(包含订单与退款等不同模块 Tool)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
import dev.langchain4j.agent.tool.Tool;

public class BusinessTools {

// ===== 订单模块 Tool =====
@Tool("校验订单ID格式与有效性")
public String validateOrder(String orderId) {
System.out.println(" --> [Tool] 执行 validateOrder: " + orderId);
return "SUCCESS: 订单 " + orderId + " 校验通过";
}

@Tool("为指定订单预留商品库存")
public String reserveInventory(String orderId) {
System.out.println(" --> [Tool] 执行 reserveInventory: " + orderId);
return "SUCCESS: 库存预留成功";
}

@Tool("执行订单扣款操作")
public String chargePayment(String orderId) {
System.out.println(" --> [Tool] 执行 chargePayment: " + orderId);
return "SUCCESS: 扣款成功";
}

@Tool("发送订单处理结果通知邮件")
public String sendConfirmationEmail(String orderId) {
System.out.println(" --> [Tool] 执行 sendConfirmationEmail: " + orderId);
return "SUCCESS: 邮件已发送";
}

@Tool("订单处理失败时执行事务回滚")
public String rollbackOrder(String orderId) {
System.out.println(" --> [Tool] 执行 rollbackOrder: " + orderId);
return "SUCCESS: 已回滚";
}

// ===== 退款模块 Tool =====
@Tool("检查订单退款资格与时效")
public String checkEligibility(String orderId) {
System.out.println(" --> [Tool] 执行 checkEligibility: " + orderId);
return "SUCCESS: 订单 " + orderId + " 符合 7 天无理由退货条件";
}

@Tool("生成退货物流面单")
public String generateReturnLabel(String orderId) {
System.out.println(" --> [Tool] 执行 generateReturnLabel: " + orderId);
return "SUCCESS: 退货面单已生成 TRACK_123456";
}

@Tool("执行向原支付渠道退款")
public String executeRefund(String orderId) {
System.out.println(" --> [Tool] 执行 executeRefund: " + orderId);
return "SUCCESS: 退款 ¥99.00 已原路退回";
}
}

改造 AI Service 接口(动态感知多 Skill 上下文)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

public interface MultiSkillAssistant {

@SystemMessage("""
你是一个多功能客服 Agent。系统中有以下可用技能目录:
{{skillSummaries}}

如果用户提出的需求命中某个技能,请严格按照以下【当前生效的 SOP 指南】来执行:
{{currentSkillSOP}}
""")
String chat(
@UserMessage String userMessage,
@V("skillSummaries") String skillSummaries,
@V("currentSkillSOP") String currentSkillSOP
);
}

组装主程序:根据意图选择匹配的 Skill

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;

/**
* @author KJ
*/
public class MultiSkillApp {

public static void main(String[] args) {
ChatModel model = OpenAiChatModel.builder()
.baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
.apiKey(System.getenv("QWEN_API_KEY"))
.modelName("qwen3.7-plus")
.temperature(0.0) // SOP 执行建议设为 0,确保行为的确定性
.logRequests(true)
.logResponses(true)
.build();

// 1. 初始化 SkillManager 并注册所有 Skill
SkillManager skillManager = new SkillManager();

AgentSkill processOrderSkill = AgentSkill.loadFromClasspath("skills/process-order/SKILL.md");
AgentSkill refundRequestSkill = AgentSkill.loadFromClasspath("skills/refund-request/SKILL.md");

skillManager.registerSkill(processOrderSkill);
skillManager.registerSkill(refundRequestSkill);

// 2. 构建 AI Service,注入全量底层工具(或通过 ToolProvider 按 Skill 过滤)
MultiSkillAssistant assistant = AiServices.builder(MultiSkillAssistant.class)
.chatModel(model)
.tools(new BusinessTools())
.build();

String skillSummaries = skillManager.getSkillSummaryList();

// ================= 场景 A:用户要求处理订单 =================
System.out.println("========== 场景 A:触发订单处理 Skill ==========");
AgentSkill activeSkillA = skillManager.getSkill("process-order");
String resA = assistant.chat(
"帮我处理一下订单 ORD001",
skillSummaries,
activeSkillA.getInstructions() // 仅注入 process-order 的 SOP
);
System.out.println("\n[LLM 最终回复]:\n" + resA);

// ================= 场景 B:用户要求申请退款 =================
System.out.println("\n========== 场景 B:触发退款申请 Skill ==========");
AgentSkill activeSkillB = skillManager.getSkill("refund-request");
String resB = assistant.chat(
"我要申请订单 ORD002 的退款",
skillSummaries,
activeSkillB.getInstructions() // 仅注入 refund-request 的 SOP
);
System.out.println("\n[LLM 最终回复]:\n" + resB);
}
}


测试结果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
========== 场景 A:触发订单处理 Skill ==========
...
--> [Tool] 执行 validateOrder: ORD001
...
--> [Tool] 执行 reserveInventory: ORD001
...
--> [Tool] 执行 chargePayment: ORD001
...
--> [Tool] 执行 sendConfirmationEmail: ORD001
...
[LLM 最终回复]:
订单 ORD001 已成功处理完成!

处理流程如下:
✓ 订单校验通过
✓ 库存预留成功
✓ 订单扣款成功
✓ 确认邮件已发送

您的订单已进入正常处理流程,请留意查收确认邮件。如有其他问题,请随时联系我。

========== 场景 B:触发退款申请 Skill ==========
...
--> [Tool] 执行 checkEligibility: ORD002
...
--> [Tool] 执行 generateReturnLabel: ORD002
...
03:08:42.677 [main] INFO dev.langchain4j.http.client.log.LoggingHttpClient -- HTTP response:
- status code: 200
- headers: [:status: 200], [content-length: 1243], [content-type: application/json],..."choices":[{"message":{"content":"太好了!您的退货物流面单已成功生成,物流单号为:**TRACK_123456**。\n\n请您使用该面单将商品寄回。以下是后续流程说明:\n\n---\n\n### 📋 退款申请进度\n\n| 步骤 | 状态 |\n|------|------|\n| ✅ 退款资格检查 | 已通过(符合7天无理由退货) |\n| ✅ 退货物流面单生成 | 已完成(单号:TRACK_123456) |\n| ⏳ 等待收到退货 | 进行中 |\n| ⏳ 执行退款 | 待处理 |\n\n---\n\n### 📌 下一步操作\n1. 请使用物流单号 **TRACK_123456** 将商品寄回。\n2. 我们确认收到退货后,将立即为您执行退款操作。\n3. 退款将原路返回至您的支付账户。\n\n如有任何问题,请随时联系我!😊","reasoning_content":"用户已经确认收到退货,现在需要执行退款操作。","role":"assistant"},"index":0,"finish_reason":"stop"}],"created":1789844918,"object":"chat.completion","usage":{"total_tokens":1239,"completion_tokens":222,"prompt_tokens":1017,"completion_tokens_details":{"reasoning_tokens":12,"text_tokens":222},"prompt_tokens_details":{"cached_tokens":512,"text_tokens":1017}}}


[LLM 最终回复]:
太好了!您的退货物流面单已成功生成,物流单号为:**TRACK_123456**。

请您使用该面单将商品寄回。以下是后续流程说明:

---

### 📋 退款申请进度

| 步骤 | 状态 |
|------|------|
| ✅ 退款资格检查 | 已通过(符合7天无理由退货) |
| ✅ 退货物流面单生成 | 已完成(单号:TRACK_123456) |
| ⏳ 等待收到退货 | 进行中 |
| ⏳ 执行退款 | 待处理 |

---

### 📌 下一步操作
1. 请使用物流单号 **TRACK_123456** 将商品寄回。
2. 我们确认收到退货后,将立即为您执行退款操作。
3. 退款将原路返回至您的支付账户。

如有任何问题,请随时联系我!😊

Process finished with exit code 0

我们看到:

  • 在处理退款(场景 B)时,系统只把 refund-request 的 3 步 SOP 传给了模型,完全没有传递 process-order 包含验证、扣款、发邮件等繁琐 SOP 的长文本。
  • 当用户做退款操作时,模型受限于 refund-request 的 SOP 指引,绝对不会跳去调用 validateOrder 或 chargePayment,保证了业务流转的准确性。
  • 今后无论新增多少个 Skill(如 issue-invoice、change-address),只需新建一个 SKILL.md 文件并向 SkillManager 注册即可,无需改动核心路由和业务代码!


实现自动判定意图

刚刚上面的测试中,我们是手动把某个 Skil 塞给 assistant.chat 接口的,但在多 Skill 架构中,手动把某个 Skill 塞给 AI 是不符合 Agent 自动化诉求的。真正的动态 Agent 机制是:Agent 先看到“技能目录”,根据用户的输入“自主判定意图”,然后自动去按需加载对应的 SKILL.md 正文并执行。

在 LangChain4j 中,实现这一机制有两种方案:

  1. 轻量路由器模式:先用一次极轻量的 LLM 调用(或关键词匹配)完成意图识别,选中 Skill 后再调用主 Agent。(推荐,省 Token 且逻辑可控)
  2. ReAct 动态工具模式:给 LLM 提供一个专门用于“激活技能”的工具,让主 Agent 在 ReAct 循环中自己决定什么时候调用该工具去读取 SKILL.md。

下面我们采用工程落地的最佳实践 ——【方案 1:轻量意图路由器 + 动态 Skill 调配】,构建一个完全可运行的 100% 自动匹配代码。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[用户输入: "我想把 ORD002 的钱退了"]
│
▼
┌──────────────┐
│ SkillRouter │ ──── (只看简短目录,耗费 ~20 Token)
└──────────────┘
│
▼
[判定结果: "refund-request"]
│
▼
[ SkillManager 加载 refund-request/SKILL.md 正文 SOP ]
│
▼
┌──────────────────────┐
│ MultiSkillAssistant │ ──── (带入对应 SOP 与 Tool 运行)
└──────────────────────┘


完整代码实现

代码结构:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
├── pom.xml
├── src
│   ├── main
│   │   ├── java
│   │   │   └── zdemo
│   │   │   ├── AgentSkill.java
│   │   │   ├── AutoSkillApp.java
│   │   │   ├── BusinessTools.java
│   │   │   ├── MultiSkillAssistant.java
│   │   │   ├── SkillManager.java
│   │   │   └── SkillRouter.java
│   │   └── resources
│   │   └── skills
│   │   ├── process-order
│   │   │   └── SKILL.md
│   │   └── refund-request
│   │   └── SKILL.md

SkillRouter:定义意图路由器接口

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

public interface SkillRouter {

@SystemMessage("""
你是一个意图分类路由器。你的唯一任务是根据用户的输入,从给定的【技能目录】中选择最匹配的一个技能名称(skill name)。

【技能目录】
{{skillSummaries}}
- NONE: 用户仅在进行闲聊、打招呼或询问通用问题,未涉及任何具体业务技能。

【要求】
1. 只允许输出匹配到的技能名称(例如 "process-order" 或 "refund-request" 或 "NONE")。
2. 严禁输出任何多余的解释、标点符号或换行符!
""")
String route(@UserMessage String userMessage, @V("skillSummaries") String skillSummaries);
}

MultiSkillAssistant:AI 助手主接口,主 Agent 用于接收动态路由好的 SOP 正文并执行:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

public interface MultiSkillAssistant {

@SystemMessage("""
你是一个专业的智能客服 Agent。

{{currentSkillSOP}}
""")
String chat(
@UserMessage String userMessage,
@V("currentSkillSOP") String currentSkillSOP
);
}

SkillManager:增强版 SkillManager(带路由与自动加载能力)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
import java.util.*;

public class SkillManager {

private final Map<String, AgentSkill> skillMap = new HashMap<>();

public void registerSkill(AgentSkill skill) {
skillMap.put(skill.getName(), skill);
}

public AgentSkill getSkill(String name) {
return skillMap.get(name);
}

/**
* 生成给 Router 看的轻量级技能目录(仅包含名称和简短描述)
*/
public String getSkillSummaryList() {
StringBuilder sb = new StringBuilder();
for (AgentSkill skill : skillMap.values()) {
sb.append("- ").append(skill.getName()).append(": ").append(skill.getDescription()).append("\n");
}
return sb.toString();
}
}

AutoSkillApp入口:这里将路由判定、Skill SOP 选取、Tool 挂载全流程自动化封装为一个入口方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.AiServices;

/**
* @author KJ
*/
public class AutoSkillApp {

private final SkillManager skillManager;
private final SkillRouter router;
private final MultiSkillAssistant assistant;

public AutoSkillApp(ChatModel model) {
// 1. 初始化 Skill 管理器并注册已知 Skill
this.skillManager = new SkillManager();
skillManager.registerSkill(AgentSkill.loadFromClasspath("skills/process-order/SKILL.md"));
skillManager.registerSkill(AgentSkill.loadFromClasspath("skills/refund-request/SKILL.md"));

// 2. 初始化 Router Agent(意图路由识别)
this.router = AiServices.builder(SkillRouter.class)
.chatModel(model)
.build();

// 3. 初始化主业务 Agent(带全量或动态 Tool 实例)
this.assistant = AiServices.builder(MultiSkillAssistant.class)
.chatModel(model)
.tools(new BusinessTools()) // 此处包含 validateOrder, executeRefund 等所有 Tool
.build();
}

/**
* 核心方法:自动路由分类 -> 动态加载 SKILL.md -> 驱动主 Agent 执行
*/
public String handleUserRequest(String userMessage) {
System.out.println("\n------------------------------------------------");
System.out.println("[用户输入]: " + userMessage);

// 第一步:获取全量技能目录概要,让 Router 进行意图判定
String summaries = skillManager.getSkillSummaryList();
String selectedSkillName = router.route(userMessage, summaries).trim();

System.out.println("[意图路由结果]: 匹配到的技能 -> " + selectedSkillName);

// 第二步:根据路由结果,动态准备 Prompt 上下文
String sopContext;
AgentSkill matchedSkill = skillManager.getSkill(selectedSkillName);

if (matchedSkill != null) {
System.out.println("[SkillManager]: 自动装载技能 SOP -> " + matchedSkill.getName());
sopContext = "【当前适用的业务 SOP 流程规范】:\n" + matchedSkill.getInstructions();
} else {
System.out.println("[SkillManager]: 未匹配到特定业务技能,按普通客服流程处理");
sopContext = "当前为日常咨询或闲聊,无需遵循特定业务 SOP,请客气周到地回答用户。";
}

// 第三步:将精准装载好的 SOP 传入主 Agent 执行业务调用
return assistant.chat(userMessage, sopContext);
}

public static void main(String[] args) {
ChatModel model = OpenAiChatModel.builder()
.baseUrl("https://dashscope.aliyuncs.com/compatible-mode/v1")
.apiKey(System.getenv("QWEN_API_KEY"))
.modelName("qwen3.7-plus")
.temperature(0.0) // SOP 执行建议设为 0,确保行为的确定性
.logRequests(true)
.logResponses(true)
.build();
AutoSkillApp app = new AutoSkillApp(model);

// 测试用例 1:触发订单处理 Skill
String answer1 = app.handleUserRequest("请帮我处理订单 ORD001");
System.out.println("\n[LLM 最终回复]:\n" + answer1);

// 测试用例 2:触发退款申请 Skill
String answer2 = app.handleUserRequest("我不想要这个东西了,帮我把订单 ORD002 退掉");
System.out.println("\n[LLM 最终回复]:\n" + answer2);

// 测试用例 3:未命中任何 Skill(闲聊/常规问答)
String answer3 = app.handleUserRequest("你们支持哪些支付方式?");
System.out.println("\n[LLM 最终回复]:\n" + answer3);
}
}


测试结果

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
------------------------------------------------
[用户输入]: 请帮我处理订单 ORD001
[意图路由结果]: 匹配到的技能 -> process-order
[SkillManager]: 自动装载技能 SOP -> process-order
--> [Tool] 执行 validateOrder: ORD001
--> [Tool] 执行 reserveInventory: ORD001
--> [Tool] 执行 chargePayment: ORD001
--> [Tool] 执行 sendConfirmationEmail: ORD001

[LLM 最终回复]:
订单 ORD001 已为您按标准流程处理完成...

------------------------------------------------
[用户输入]: 我不想要这个东西了,帮我把订单 ORD002 退掉
[意图路由结果]: 匹配到的技能 -> refund-request
[SkillManager]: 自动装载技能 SOP -> refund-request
--> [Tool] 执行 checkEligibility: ORD002
--> [Tool] 执行 generateReturnLabel: ORD002
--> [Tool] 执行 executeRefund: ORD002

[LLM 最终回复]:
已为您提交订单 ORD002 的退款申请,退货面单号为 TRACK_123456...

------------------------------------------------
[用户输入]: 你们支持哪些支付方式?
[意图路由结果]: 匹配到的技能 -> NONE
[SkillManager]: 未匹配到特定业务技能,按普通客服流程处理

[LLM 最终回复]:
我们目前支持微信支付、支付宝、银联卡以及各大主流信用卡支付。请问有什么我可以帮您的吗?

这种设计模式的核心优势:

  • 精准控制 Token 消耗:第一阶段路由(Router)消耗极少(几十 Tokens);第二阶段主 Agent 只加载选中的单一 SKILL.md,彻底解决了多个业务 SOP 混在一起导致 Context 爆炸的问题。
  • 零硬编码扩展:以后新增 Skill(比如 change-address),只需在类路径下放一个新的 skills/change-address/SKILL.md 并在 SkillManager 注册即可,路由与装载逻辑完全通用。
  • 消除 LLM 幻觉:在做退款任务时,主 Agent 的 Prompt 里完全没有订单扣款或发送确认邮件的 SOP 规范,从根本上杜绝了 LLM 跨业务流程误操作的可能性。


对 MCP 的支持

另外,LangChain4j 完全可以通过集成 MCP 来为 Agent 提供和加载 Skill。传统上,SKILL 通常以本地 SKILL.md(Prompt SOP + 本地 Java @Tool)的形式存在。而在 MCP 架构下,Skill 被进一步微服务化/解耦化:

  • MCP Tool 充当动态技能组件:MCP 服务端(MCP Server)可以向 LangChain4j 客户端动态暴露 Tools、Prompts(即 SOP 模版)以及 Resources。
  • 免编译、动态接入:LangChain4j 可以在运行时通过 McpToolProvider 或 McpClient 从远程或本地 MCP Server 动态拉取最新的工具定义和提示词。新增或修改一个 Skill,完全不需要重新编译 Java 代码或重启服务。


代码示例

1
2
3
4
5
<dependency>
<groupId>dev.langchain4j</groupId>
<artifactId>langchain4j-mcp</artifactId>
<version>1.17.2-beta27</version>
</dependency>

在 LangChain4j 中,结合 MCP 加载 Skill 工具主要有两种常见模式:

方案 1:静态/启动时绑定 MCP Skill Tools

如果你的 MCP Server(比如一个专门处理订单业务的 order-mcp-server)提供了该 Skill 所需的所有工具,可以直接将其转为 LangChain4j 的 ToolProvider:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import dev.langchain4j.mcp.McpToolProvider;
import dev.langchain4j.mcp.client.DefaultMcpClient;
import dev.langchain4j.mcp.client.McpClient;
import dev.langchain4j.mcp.client.transport.stdio.StdioMcpTransport;
import dev.langchain4j.service.AiServices;
import java.time.Duration;
import java.util.List;

public class McpSkillExample {

public static void main(String[] args) {
// 1. 初始化 MCP Client(支持 StdioTransport 或 SseTransport)
McpClient mcpClient = new DefaultMcpClient.Builder()
.transport(new StdioMcpTransport.Builder()
.command(List.of("node", "/path/to/order-skill-mcp-server/index.js"))
.build())
.toolExecutionTimeout(Duration.ofSeconds(30))
.build();

// 2. 将 MCP Client 封装为 ToolProvider(自动同步 MCP 中的所有技能工具)
McpToolProvider toolProvider = McpToolProvider.builder()
.mcpClients(List.of(mcpClient))
.build();

// 3. 构造主 Agent
OrderAgent agent = AiServices.builder(OrderAgent.class)
.chatLanguageModel(model)
.toolProvider(toolProvider) // 注入 MCP 提供者
.build();

// 4. 调用 Agent 执行业务
String response = agent.chat("请帮我处理订单 ORD001");
System.out.println(response);
}
}

方案 2:基于意图路由动态选择并加载 MCP Skill(最佳实践)

如果存在多个 MCP Server(例如 order-mcp-server、refund-mcp-server、inventory-mcp-server),且你不希望一次性把所有 MCP 工具都透出给 LLM(避免 Token 浪费与幻觉),结合前面的路由机制,可以在运行时动态按需选择 MCP 工具:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import dev.langchain4j.agent.tool.ToolSpecification;
import dev.langchain4j.mcp.client.McpClient;
import dev.langchain4j.service.tool.ToolProvider;
import dev.langchain4j.service.tool.ToolProviderRequest;
import dev.langchain4j.service.tool.ToolProviderResult;
import zdemo.SkillRouter;
import java.util.List;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

public class DynamicMcpSkillToolProvider implements ToolProvider {

private final SkillRouter router;
private final Map<String, McpClient> mcpSkillClients = new ConcurrentHashMap<>();

public DynamicMcpSkillToolProvider(SkillRouter router) {
this.router = router;
// 初始化各个 MCP 客户端 (例如通过 SSE 连接不同的 MCP 技能微服务)
mcpSkillClients.put("process-order", createMcpClient("http://mcp-order-service/sse"));
mcpSkillClients.put("refund-request", createMcpClient("http://mcp-refund-service/sse"));
}

@Override
public ToolProviderResult provideTools(ToolProviderRequest request) {
String userMessage = request.userMessage().singleText();

// 1. 先用轻量 Router 判定意图
String matchedSkill = router.route(userMessage);

// 2. 如果判定命中某个 MCP Skill,则仅提取并暴露该 MCP 服务端的 Tools
McpClient mcpClient = mcpSkillClients.get(matchedSkill);
if (mcpClient != null) {
// 从对应的 MCP Server 动态获取工具定义
List<ToolSpecification> tools = mcpClient.listTools();
return ToolProviderResult.builder()
.addTools(tools)
.build();
}

// 3. 未命中或闲聊场景:不暴露任何 MCP 工具
return ToolProviderResult.builder().build();
}
}


实践套路

  • MCP Prompts 与 SKILL.md 的映射:MCP 协议自带 Prompts 规范(prompts/list 与 prompts/get)。你可以把 SKILL.md 中的标准 SOP 写入 MCP Server 的 Prompt 定义中。LangChain4j Agent 在激活某个 Skill 时,通过 MCP 获取对应的 System Prompt SOP + Tool 列表,实现 SOP 与工具的全套动态装载。
  • 传输协议选择:如果是本地/单体部署,使用 StdioMcpTransport(通过子进程 stdin/stdout 通信),适合与本地 Python/Node.js 编写的技能工具配合;如果是分布式微服务,使用 SseMcpTransport(基于 HTTP Server-Sent Events),将 Skill 工具打包成独立的云端微服务,LangChain4j 作为 MCP Client 远程调用。